home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / gnu / amiga / gnnln920.lha / README < prev   
Text File  |  1992-06-14  |  5KB  |  130 lines
  1. This is the second release of the inline header generator. Sorry for
  2. the previous version, it was rather buggy.. (hardly any generated
  3. entry vector was right, damn bug in the converter ..).
  4.  
  5. **************************************************************************
  6.  
  7. The converter `conv.p' included in this package is free software; you can
  8. redistribute it and/or modify it under the terms of the GNU General Public
  9. License as published by the Free Software Foundation; either version 2, or
  10. (at your option) any later version.
  11.  
  12. conv.p is distributed in the hope that it will be useful, but WITHOUT ANY
  13. WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  14. FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  15. details.
  16.  
  17. You should have received a copy of the GNU General Public License along
  18. with conv.p; see the file COPYING.  If not, write to the Free Software
  19. Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  20.  
  21. **************************************************************************
  22.  
  23.  
  24. The converter itself is my first attempt in programming Perl, so please
  25. bear with some kludy or inefficient (? please tell me ;-)) parts.
  26.  
  27.  
  28. (Please don't ask me to provide you with a copy of Perl. The version I
  29. have is in no way a current version, I had the sources laying around on
  30. my harddisk very long until I compiled it. There should be much newer
  31. versions out there by now.)
  32.  
  33.  
  34. Writing such a converter is not necessarily a trivial task, just consider
  35. that you have to take something like 
  36.  
  37.   APTR SetFunction( struct Library *library, long funcOffset,
  38.     unsigned long (*newFunction)() );
  39.  
  40. as input, remove the argument names (because you can't rely on them, they're
  41. optional!), insert (at the right place...) the argument names from the
  42. fd files, and then go ahead and write a function for this beast...
  43.  
  44. I tested this converter on Commodore clib/ prototype headers, the inline
  45. headers included in this distribution are are the result of this test. They
  46. were slightly hand editted in those ~5 cases where the converter issued a
  47. warning that either A4 or A5 is spilled, to save those registers on the
  48. stack before clobbering them. Another fix was necessary to mathffp.h, since
  49. the fd files for Sub and Div still contain the wrong registers... There's
  50. a last spot that needed intervention, and that's the declaration of this
  51. function:
  52.  
  53.   void SetCollision( unsigned long num,
  54.     void (*routine)(struct VSprite *vSprite, APTR),
  55.     struct GelsInfo *gelsInfo );
  56.  
  57. the converter doesn't yet understand full ANSI declarations, it relies on
  58. the fact that it is able to split the argument line at every comma, which
  59. generates a wrong result in this case. The solution is to rewrite this
  60. declaration as:
  61.  
  62.   void SetCollision( unsigned long num,
  63.     void (*routine)(),
  64.     struct GelsInfo *gelsInfo );
  65.  
  66. and then the converter has no problems parsing it. (If you feel like you
  67. want the converter to be able to recognise full ANSI syntax, go ahead. But
  68. keep in mind that you not only have to add fancier argument splitting, but
  69. also add more intelligence to the part that inserts the right argument
  70. names into the declaration..).
  71.  
  72. If you want to run the converter on your own library- and fd-files, the
  73. following strategy should give best results:
  74.  
  75.   | create/use a prototype file that contains mostly function declarations.
  76.   | The converter logic is *not* a full blown C compiler, it works best
  77.   | when used in the context where it was made for. If you feed it with
  78.   | nonsense, all hell can get lose, you may get no output at all, you
  79.   | may get wrong output, just use your imagination ;-))
  80.  
  81. Then try to convert with:
  82.  
  83.   perl conv.p your_headerfile your_fdfile
  84.  
  85. and look at the generated output.  You can then redirect the output to a
  86. file if you think the generated code seems correct.
  87.  
  88.  
  89. Some notes to gcc-1.40 users
  90. ----------------------------
  91. The generated inline headers of this converter won't run on 1.40. This is
  92. simply because I chose to write declarations as
  93.  
  94.   register int d2 asm ("d2") = foo;
  95.  
  96. instead of in the older style:
  97.  
  98.   register int d2 asm ("d2");
  99.   ....
  100.   d2 = foo;
  101.  
  102. The new style is more compact and should help people that are short on
  103. memory. If you absolutely need the older style, change the conv.p script
  104. to output it, this shouldn't be too difficult.
  105.  
  106.  
  107. Explanation for those __BEGIN_DECLS and __END_DECLS
  108. ---------------------------------------------------
  109. All headers now include <sys/cdefs.h> to define those two macros. Their
  110. effect depends on whether running under C or C++. If running under C,
  111. they expand into nothing. Under C++ however they build an
  112.  
  113.   extern "C" {
  114.   ...
  115.   };
  116.  
  117. block to make sure that the functions are generated with C linkage rules.
  118.  
  119.  
  120. Well.. now it's your part! I already found lots of headers in the (short)
  121. history of this converter, that it didn't parse correctly. These headers
  122. always lead to a change of some regular expressions in the converter, and
  123. I'm pretty sure it needs some more of those changes ;-)) If you have such
  124. header files, and you can fix the converter to accept them, please send
  125. me the diffs!
  126.  
  127. -Markus
  128.  
  129. <wild@nessie.cs.id.ethz.ch> or <wild@amiga.physik.unizh.ch>
  130.